/*
 * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.xml.datatype;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;

import javax.xml.namespace.QName;

/**
 * <p>Immutable representation of a time span as defined in
 * the W3C XML Schema 1.0 specification.</p>
 *
 * <p>A Duration object represents a period of Gregorian time,
 * which consists of six fields (years, months, days, hours,
 * minutes, and seconds) plus a sign (+/-) field.</p>
 *
 * <p>The first five fields have non-negative (>=0) integers or null
 * (which represents that the field is not set),
 * and the seconds field has a non-negative decimal or null.
 * A negative sign indicates a negative duration.</p>
 *
 * <p>This class provides a number of methods that make it easy
 * to use for the duration datatype of XML Schema 1.0 with
 * the errata.</p>
 *
 * <h2>Order relationship</h2>
 * <p>Duration objects only have partial order, where two values A and B
 * maybe either:</p>
 * <ol>
 * <li>A&lt;B (A is shorter than B)
 * <li>A&gt;B (A is longer than B)
 * <li>A==B   (A and B are of the same duration)
 * <li>A&lt;>B (Comparison between A and B is indeterminate)
 * </ol>
 *
 * <p>For example, 30 days cannot be meaningfully compared to one month.
 * The {@link #compare(Duration duration)} method implements this
 * relationship.</p>
 *
 * <p>See the {@link #isLongerThan(Duration)} method for details about
 * the order relationship among <code>Duration</code> objects.</p>
 *
 * <h2>Operations over Duration</h2>
 * <p>This class provides a set of basic arithmetic operations, such
 * as addition, subtraction and multiplication.
 * Because durations don't have total order, an operation could
 * fail for some combinations of operations. For example, you cannot
 * subtract 15 days from 1 month. See the javadoc of those methods
 * for detailed conditions where this could happen.</p>
 *
 * <p>Also, division of a duration by a number is not provided because
 * the <code>Duration</code> class can only deal with finite precision
 * decimal numbers. For example, one cannot represent 1 sec divided by 3.</p>
 *
 * <p>However, you could substitute a division by 3 with multiplying
 * by numbers such as 0.3 or 0.333.</p>
 *
 * <h2>Range of allowed values</h2>
 * <p>
 * Because some operations of <code>Duration</code> rely on {@link Calendar}
 * even though {@link Duration} can hold very large or very small values,
 * some of the methods may not work correctly on such <code>Duration</code>s.
 * The impacted methods document their dependency on {@link Calendar}.
 *
 * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
 * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a>
 * @see XMLGregorianCalendar#add(Duration)
 * @since 1.5
 */
public abstract class Duration {

  /**
   * <p>Debugging <code>true</code> or <code>false</code>.</p>
   */
  private static final boolean DEBUG = true;

  /**
   * Default no-arg constructor.
   *
   * <p>Note: Always use the {@link DatatypeFactory} to
   * construct an instance of <code>Duration</code>.
   * The constructor on this class cannot be guaranteed to
   * produce an object with a consistent state and may be
   * removed in the future.</p>
   */
  public Duration() {
  }

  /**
   * <p>Return the name of the XML Schema date/time type that this instance
   * maps to. Type is computed based on fields that are set,
   * i.e. {@link #isSet(DatatypeConstants.Field field)} == <code>true</code>.</p>
   *
   * <table border="2" rules="all" cellpadding="2">
   * <thead>
   * <tr>
   * <th align="center" colspan="7">
   * Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
   * <i>(timezone is optional for all date/time datatypes)</i>
   * </th>
   * </tr>
   * </thead>
   * <tbody>
   * <tr>
   * <td>Datatype</td>
   * <td>year</td>
   * <td>month</td>
   * <td>day</td>
   * <td>hour</td>
   * <td>minute</td>
   * <td>second</td>
   * </tr>
   * <tr>
   * <td>{@link DatatypeConstants#DURATION}</td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * </tr>
   * <tr>
   * <td>{@link DatatypeConstants#DURATION_DAYTIME}</td>
   * <td></td>
   * <td></td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * <td>X</td>
   * </tr>
   * <tr>
   * <td>{@link DatatypeConstants#DURATION_YEARMONTH}</td>
   * <td>X</td>
   * <td>X</td>
   * <td></td>
   * <td></td>
   * <td></td>
   * <td></td>
   * </tr>
   * </tbody>
   * </table>
   *
   * @return one of the following constants: {@link DatatypeConstants#DURATION}, {@link
   * DatatypeConstants#DURATION_DAYTIME} or {@link DatatypeConstants#DURATION_YEARMONTH}.
   * @throws IllegalStateException If the combination of set fields does not match one of the XML
   * Schema date/time datatypes.
   */
  public QName getXMLSchemaType() {

    boolean yearSet = isSet(DatatypeConstants.YEARS);
    boolean monthSet = isSet(DatatypeConstants.MONTHS);
    boolean daySet = isSet(DatatypeConstants.DAYS);
    boolean hourSet = isSet(DatatypeConstants.HOURS);
    boolean minuteSet = isSet(DatatypeConstants.MINUTES);
    boolean secondSet = isSet(DatatypeConstants.SECONDS);

    // DURATION
    if (yearSet
        && monthSet
        && daySet
        && hourSet
        && minuteSet
        && secondSet) {
      return DatatypeConstants.DURATION;
    }

    // DURATION_DAYTIME
    if (!yearSet
        && !monthSet
        && daySet
        && hourSet
        && minuteSet
        && secondSet) {
      return DatatypeConstants.DURATION_DAYTIME;
    }

    // DURATION_YEARMONTH
    if (yearSet
        && monthSet
        && !daySet
        && !hourSet
        && !minuteSet
        && !secondSet) {
      return DatatypeConstants.DURATION_YEARMONTH;
    }

    // nothing matches
    throw new IllegalStateException(
        "javax.xml.datatype.Duration#getXMLSchemaType():"
            + " this Duration does not match one of the XML Schema date/time datatypes:"
            + " year set = " + yearSet
            + " month set = " + monthSet
            + " day set = " + daySet
            + " hour set = " + hourSet
            + " minute set = " + minuteSet
            + " second set = " + secondSet
    );
  }

  /**
   * Returns the sign of this duration in -1,0, or 1.
   *
   * @return -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is
   * positive.
   */
  public abstract int getSign();

  /**
   * <p>Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code>
   * if not present.</p>
   *
   * <p><code>getYears()</code> is a convenience method for {@link #getField(DatatypeConstants.Field
   * field) getField(DatatypeConstants.YEARS)}.</p>
   *
   * <p>As the return value is an <code>int</code>, an incorrect value will be returned for
   * <code>Duration</code>s with years that go beyond the range of an <code>int</code>. Use {@link
   * #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible
   * loss of precision.</p>
   *
   * @return If the years field is present, return its value as an <code>int</code>, else return
   * <code>0</code>.
   */
  public int getYears() {
    return getField(DatatypeConstants.YEARS).intValue();
  }

  /**
   * Obtains the value of the MONTHS field as an integer value,
   * or 0 if not present.
   *
   * This method works just like {@link #getYears()} except
   * that this method works on the MONTHS field.
   *
   * @return Months of this <code>Duration</code>.
   */
  public int getMonths() {
    return getField(DatatypeConstants.MONTHS).intValue();
  }

  /**
   * Obtains the value of the DAYS field as an integer value,
   * or 0 if not present.
   *
   * This method works just like {@link #getYears()} except
   * that this method works on the DAYS field.
   *
   * @return Days of this <code>Duration</code>.
   */
  public int getDays() {
    return getField(DatatypeConstants.DAYS).intValue();
  }

  /**
   * Obtains the value of the HOURS field as an integer value,
   * or 0 if not present.
   *
   * This method works just like {@link #getYears()} except
   * that this method works on the HOURS field.
   *
   * @return Hours of this <code>Duration</code>.
   */
  public int getHours() {
    return getField(DatatypeConstants.HOURS).intValue();
  }

  /**
   * Obtains the value of the MINUTES field as an integer value,
   * or 0 if not present.
   *
   * This method works just like {@link #getYears()} except
   * that this method works on the MINUTES field.
   *
   * @return Minutes of this <code>Duration</code>.
   */
  public int getMinutes() {
    return getField(DatatypeConstants.MINUTES).intValue();
  }

  /**
   * Obtains the value of the SECONDS field as an integer value,
   * or 0 if not present.
   *
   * This method works just like {@link #getYears()} except
   * that this method works on the SECONDS field.
   *
   * @return seconds in the integer value. The fraction of seconds will be discarded (for example,
   * if the actual value is 2.5, this method returns 2)
   */
  public int getSeconds() {
    return getField(DatatypeConstants.SECONDS).intValue();
  }

  /**
   * <p>Returns the length of the duration in milli-seconds.</p>
   *
   * <p>If the seconds field carries more digits than milli-second order,
   * those will be simply discarded (or in other words, rounded to zero.)
   * For example, for any Calendar value <code>x</code>,</p>
   * <pre>
   * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
   * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
   * </pre>
   *
   * <p>
   * Note that this method uses the {@link #addTo(Calendar)} method,
   * which may work incorrectly with <code>Duration</code> objects with
   * very large values in its fields. See the {@link #addTo(Calendar)}
   * method for details.
   *
   * @param startInstant The length of a month/year varies. The <code>startInstant</code> is used to
   * disambiguate this variance. Specifically, this method returns the difference between
   * <code>startInstant</code> and <code>startInstant+duration</code>
   * @return milliseconds between <code>startInstant</code> and <code>startInstant</code> plus this
   * <code>Duration</code>
   * @throws NullPointerException if <code>startInstant</code> parameter is null.
   */
  public long getTimeInMillis(final Calendar startInstant) {
    Calendar cal = (Calendar) startInstant.clone();
    addTo(cal);
    return getCalendarTimeInMillis(cal)
        - getCalendarTimeInMillis(startInstant);
  }

  /**
   * <p>Returns the length of the duration in milli-seconds.</p>
   *
   * <p>If the seconds field carries more digits than milli-second order,
   * those will be simply discarded (or in other words, rounded to zero.)
   * For example, for any <code>Date</code> value <code>x</code>,</p>
   * <pre>
   * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
   * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
   * </pre>
   *
   * <p>
   * Note that this method uses the {@link #addTo(Date)} method,
   * which may work incorrectly with <code>Duration</code> objects with
   * very large values in its fields. See the {@link #addTo(Date)}
   * method for details.
   *
   * @param startInstant The length of a month/year varies. The <code>startInstant</code> is used to
   * disambiguate this variance. Specifically, this method returns the difference between
   * <code>startInstant</code> and <code>startInstant+duration</code>.
   * @return milliseconds between <code>startInstant</code> and <code>startInstant</code> plus this
   * <code>Duration</code>
   * @throws NullPointerException If the startInstant parameter is null.
   * @see #getTimeInMillis(Calendar)
   */
  public long getTimeInMillis(final Date startInstant) {
    Calendar cal = new GregorianCalendar();
    cal.setTime(startInstant);
    this.addTo(cal);
    return getCalendarTimeInMillis(cal) - startInstant.getTime();
  }

  /**
   * Gets the value of a field.
   *
   * Fields of a duration object may contain arbitrary large value.
   * Therefore this method is designed to return a {@link Number} object.
   *
   * In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned
   * number will be a non-negative integer. In case of seconds,
   * the returned number may be a non-negative decimal value.
   *
   * @param field one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
   * @return If the specified field is present, this method returns a non-null non-negative {@link
   * Number} object that represents its value. If it is not present, return null. For YEARS, MONTHS,
   * DAYS, HOURS, and MINUTES, this method returns a {@link java.math.BigInteger} object. For
   * SECONDS, this method returns a {@link java.math.BigDecimal}.
   * @throws NullPointerException If the <code>field</code> is <code>null</code>.
   */
  public abstract Number getField(final DatatypeConstants.Field field);

  /**
   * Checks if a field is set.
   *
   * A field of a duration object may or may not be present.
   * This method can be used to test if a field is present.
   *
   * @param field one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
   * @return true if the field is present. false if not.
   * @throws NullPointerException If the field parameter is null.
   */
  public abstract boolean isSet(final DatatypeConstants.Field field);

  /**
   * <p>Computes a new duration whose value is <code>this+rhs</code>.</p>
   *
   * <p>For example,</p>
   * <pre>
   * "1 day" + "-3 days" = "-2 days"
   * "1 year" + "1 day" = "1 year and 1 day"
   * "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
   * "15 hours" + "-3 days" = "-(2 days,9 hours)"
   * "1 year" + "-1 day" = IllegalStateException
   * </pre>
   *
   * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
   * there are cases where the operation fails in
   * {@link IllegalStateException}.</p>
   *
   * <p>
   * Formally, the computation is defined as follows.</p>
   * <p>
   * Firstly, we can assume that two <code>Duration</code>s to be added
   * are both positive without losing generality (i.e.,
   * <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>,
   * <code>(-X)+(-Y)=-(X+Y)</code>)
   *
   * <p>
   * Addition of two positive <code>Duration</code>s are simply defined as
   * field by field addition where missing fields are treated as 0.
   * <p>
   * A field of the resulting <code>Duration</code> will be unset if and
   * only if respective fields of two input <code>Duration</code>s are unset.
   * <p>
   * Note that <code>lhs.add(rhs)</code> will be always successful if
   * <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are
   * normalized.</p>
   *
   * @param rhs <code>Duration</code> to add to this <code>Duration</code>
   * @return non-null valid Duration object.
   * @throws NullPointerException If the rhs parameter is null.
   * @throws IllegalStateException If two durations cannot be meaningfully added. For example,
   * adding negative one day to one month causes this exception.
   * @see #subtract(Duration)
   */
  public abstract Duration add(final Duration rhs);

  /**
   * Adds this duration to a {@link Calendar} object.
   *
   * <p>
   * Calls {@link java.util.Calendar#add(int, int)} in the
   * order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS
   * if those fields are present. Because the {@link Calendar} class
   * uses int to hold values, there are cases where this method
   * won't work correctly (for example if values of fields
   * exceed the range of int.)
   * </p>
   *
   * <p>
   * Also, since this duration class is a Gregorian duration, this
   * method will not work correctly if the given {@link Calendar}
   * object is based on some other calendar systems.
   * </p>
   *
   * <p>
   * Any fractional parts of this <code>Duration</code> object
   * beyond milliseconds will be simply ignored. For example, if
   * this duration is "P1.23456S", then 1 is added to SECONDS,
   * 234 is added to MILLISECONDS, and the rest will be unused.
   * </p>
   *
   * <p>
   * Note that because {@link Calendar#add(int, int)} is using
   * <code>int</code>, <code>Duration</code> with values beyond the
   * range of <code>int</code> in its fields
   * will cause overflow/underflow to the given {@link Calendar}.
   * {@link XMLGregorianCalendar#add(Duration)} provides the same
   * basic operation as this method while avoiding
   * the overflow/underflow issues.
   *
   * @param calendar A calendar object whose value will be modified.
   * @throws NullPointerException if the calendar parameter is null.
   */
  public abstract void addTo(Calendar calendar);

  /**
   * Adds this duration to a {@link Date} object.
   *
   * <p>
   * The given date is first converted into
   * a {@link java.util.GregorianCalendar}, then the duration
   * is added exactly like the {@link #addTo(Calendar)} method.
   *
   * <p>
   * The updated time instant is then converted back into a
   * {@link Date} object and used to update the given {@link Date} object.
   *
   * <p>
   * This somewhat redundant computation is necessary to unambiguously
   * determine the duration of months and years.
   *
   * @param date A date object whose value will be modified.
   * @throws NullPointerException if the date parameter is null.
   */
  public void addTo(Date date) {

    // check data parameter
    if (date == null) {
      throw new NullPointerException(
          "Cannot call "
              + this.getClass().getName()
              + "#addTo(Date date) with date == null."
      );
    }

    Calendar cal = new GregorianCalendar();
    cal.setTime(date);
    this.addTo(cal);
    date.setTime(getCalendarTimeInMillis(cal));
  }

  /**
   * <p>Computes a new duration whose value is <code>this-rhs</code>.</p>
   *
   * <p>For example:</p>
   * <pre>
   * "1 day" - "-3 days" = "4 days"
   * "1 year" - "1 day" = IllegalStateException
   * "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
   * "15 hours" - "-3 days" = "3 days and 15 hours"
   * "1 year" - "-1 day" = "1 year and 1 day"
   * </pre>
   *
   * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
   * there are cases where the operation fails in {@link IllegalStateException}.</p>
   *
   * <p>Formally the computation is defined as follows.
   * First, we can assume that two <code>Duration</code>s are both positive
   * without losing generality.  (i.e.,
   * <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>,
   * <code>(-X)-(-Y)=-(X-Y)</code>)</p>
   *
   * <p>Then two durations are subtracted field by field.
   * If the sign of any non-zero field <code>F</code> is different from
   * the sign of the most significant field,
   * 1 (if <code>F</code> is negative) or -1 (otherwise)
   * will be borrowed from the next bigger unit of <code>F</code>.</p>
   *
   * <p>This process is repeated until all the non-zero fields have
   * the same sign.</p>
   *
   * <p>If a borrow occurs in the days field (in other words, if
   * the computation needs to borrow 1 or -1 month to compensate
   * days), then the computation fails by throwing an
   * {@link IllegalStateException}.</p>
   *
   * @param rhs <code>Duration</code> to subtract from this <code>Duration</code>.
   * @return New <code>Duration</code> created from subtracting <code>rhs</code> from this
   * <code>Duration</code>.
   * @throws IllegalStateException If two durations cannot be meaningfully subtracted. For example,
   * subtracting one day from one month causes this exception.
   * @throws NullPointerException If the rhs parameter is null.
   * @see #add(Duration)
   */
  public Duration subtract(final Duration rhs) {
    return add(rhs.negate());
  }

  /**
   * <p>Computes a new duration whose value is <code>factor</code> times
   * longer than the value of this duration.</p>
   *
   * <p>This method is provided for the convenience.
   * It is functionally equivalent to the following code:</p>
   * <pre>
   * multiply(new BigDecimal(String.valueOf(factor)))
   * </pre>
   *
   * @param factor Factor times longer of new <code>Duration</code> to create.
   * @return New <code>Duration</code> that is <code>factor</code>times longer than this
   * <code>Duration</code>.
   * @see #multiply(BigDecimal)
   */
  public Duration multiply(int factor) {
    return multiply(new BigDecimal(String.valueOf(factor)));
  }

  /**
   * Computes a new duration whose value is <code>factor</code> times
   * longer than the value of this duration.
   *
   * <p>
   * For example,
   * <pre>
   * "P1M" (1 month) * "12" = "P12M" (12 months)
   * "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
   * "P1M" (1 month) * "1.5" = IllegalStateException
   * </pre>
   *
   * <p>
   * Since the <code>Duration</code> class is immutable, this method
   * doesn't change the value of this object. It simply computes
   * a new Duration object and returns it.
   *
   * <p>
   * The operation will be performed field by field with the precision
   * of {@link BigDecimal}. Since all the fields except seconds are
   * restricted to hold integers,
   * any fraction produced by the computation will be
   * carried down toward the next lower unit. For example,
   * if you multiply "P1D" (1 day) with "0.5", then it will be 0.5 day,
   * which will be carried down to "PT12H" (12 hours).
   * When fractions of month cannot be meaningfully carried down
   * to days, or year to months, this will cause an
   * {@link IllegalStateException} to be thrown.
   * For example if you multiple one month by 0.5.</p>
   *
   * <p>
   * To avoid {@link IllegalStateException}, use
   * the {@link #normalizeWith(Calendar)} method to remove the years
   * and months fields.
   *
   * @param factor to multiply by
   * @return returns a non-null valid <code>Duration</code> object
   * @throws IllegalStateException if operation produces fraction in the months field.
   * @throws NullPointerException if the <code>factor</code> parameter is <code>null</code>.
   */
  public abstract Duration multiply(final BigDecimal factor);

  /**
   * Returns a new <code>Duration</code> object whose
   * value is <code>-this</code>.
   *
   * <p>
   * Since the <code>Duration</code> class is immutable, this method
   * doesn't change the value of this object. It simply computes
   * a new Duration object and returns it.
   *
   * @return always return a non-null valid <code>Duration</code> object.
   */
  public abstract Duration negate();

  /**
   * <p>Converts the years and months fields into the days field
   * by using a specific time instant as the reference point.</p>
   *
   * <p>For example, duration of one month normalizes to 31 days
   * given the start time instance "July 8th 2003, 17:40:32".</p>
   *
   * <p>Formally, the computation is done as follows:</p>
   * <ol>
   * <li>the given Calendar object is cloned</li>
   * <li>the years, months and days fields will be added to the {@link Calendar} object
   * by using the {@link Calendar#add(int, int)} method</li>
   * <li>the difference between the two Calendars in computed in milliseconds and converted to days,
   * if a remainder occurs due to Daylight Savings Time, it is discarded</li>
   * <li>the computed days, along with the hours, minutes and seconds
   * fields of this duration object is used to construct a new
   * Duration object.</li>
   * </ol>
   *
   * <p>Note that since the Calendar class uses <code>int</code> to
   * hold the value of year and month, this method may produce
   * an unexpected result if this duration object holds
   * a very large value in the years or months fields.</p>
   *
   * @param startTimeInstant <code>Calendar</code> reference point.
   * @return <code>Duration</code> of years and months of this <code>Duration</code> as days.
   * @throws NullPointerException If the startTimeInstant parameter is null.
   */
  public abstract Duration normalizeWith(final Calendar startTimeInstant);

  /**
   * <p>Partial order relation comparison with this <code>Duration</code> instance.</p>
   *
   * <p>Comparison result must be in accordance with <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C
   * XML Schema 1.0 Part 2, Section 3.2.7.6.2, <i>Order relation on duration</i></a>.</p>
   *
   * <p>Return:</p> <ul> <li>{@link DatatypeConstants#LESSER} if this <code>Duration</code> is
   * shorter than <code>duration</code> parameter</li> <li>{@link DatatypeConstants#EQUAL} if this
   * <code>Duration</code> is equal to <code>duration</code> parameter</li> <li>{@link
   * DatatypeConstants#GREATER} if this <code>Duration</code> is longer than <code>duration</code>
   * parameter</li> <li>{@link DatatypeConstants#INDETERMINATE} if a conclusive partial order
   * relation cannot be determined</li> </ul>
   *
   * @param duration to compare
   * @return the relationship between <code>this</code> <code>Duration</code>and
   * <code>duration</code> parameter as {@link DatatypeConstants#LESSER}, {@link
   * DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER} or {@link
   * DatatypeConstants#INDETERMINATE}.
   * @throws UnsupportedOperationException If the underlying implementation cannot reasonably
   * process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the
   * request may be beyond the implementations capability.
   * @throws NullPointerException if <code>duration</code> is <code>null</code>.
   * @see #isShorterThan(Duration)
   * @see #isLongerThan(Duration)
   */
  public abstract int compare(final Duration duration);

  /**
   * <p>Checks if this duration object is strictly longer than
   * another <code>Duration</code> object.</p>
   *
   * <p>Duration X is "longer" than Y if and only if X>Y
   * as defined in the section 3.2.6.2 of the XML Schema 1.0
   * specification.</p>
   *
   * <p>For example, "P1D" (one day) > "PT12H" (12 hours) and
   * "P2Y" (two years) > "P23M" (23 months).</p>
   *
   * @param duration <code>Duration</code> to test this <code>Duration</code> against.
   * @return true if the duration represented by this object is longer than the given duration.
   * false otherwise.
   * @throws UnsupportedOperationException If the underlying implementation cannot reasonably
   * process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the
   * request may be beyond the implementations capability.
   * @throws NullPointerException If <code>duration</code> is null.
   * @see #isShorterThan(Duration)
   * @see #compare(Duration duration)
   */
  public boolean isLongerThan(final Duration duration) {
    return compare(duration) == DatatypeConstants.GREATER;
  }

  /**
   * <p>Checks if this duration object is strictly shorter than
   * another <code>Duration</code> object.</p>
   *
   * @param duration <code>Duration</code> to test this <code>Duration</code> against.
   * @return <code>true</code> if <code>duration</code> parameter is shorter than this
   * <code>Duration</code>, else <code>false</code>.
   * @throws UnsupportedOperationException If the underlying implementation cannot reasonably
   * process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the
   * request may be beyond the implementations capability.
   * @throws NullPointerException if <code>duration</code> is null.
   * @see #isLongerThan(Duration duration)
   * @see #compare(Duration duration)
   */
  public boolean isShorterThan(final Duration duration) {
    return compare(duration) == DatatypeConstants.LESSER;
  }

  /**
   * <p>Checks if this duration object has the same duration
   * as another <code>Duration</code> object.</p>
   *
   * <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).</p>
   *
   * <p>Duration X is equal to Y if and only if time instant
   * t+X and t+Y are the same for all the test time instants
   * specified in the section 3.2.6.2 of the XML Schema 1.0
   * specification.</p>
   *
   * <p>Note that there are cases where two <code>Duration</code>s are
   * "incomparable" to each other, like one month and 30 days.
   * For example,</p>
   * <pre>
   * !new Duration("P1M").isShorterThan(new Duration("P30D"))
   * !new Duration("P1M").isLongerThan(new Duration("P30D"))
   * !new Duration("P1M").equals(new Duration("P30D"))
   * </pre>
   *
   * @param duration The object to compare this <code>Duration</code> against.
   * @return <code>true</code> if this duration is the same length as <code>duration</code>.
   * <code>false</code> if <code>duration</code> is <code>null</code>, is not a
   * <code>Duration</code> object, or its length is different from this duration.
   * @throws UnsupportedOperationException If the underlying implementation cannot reasonably
   * process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the
   * request may be beyond the implementations capability.
   * @see #compare(Duration duration)
   */
  public boolean equals(final Object duration) {

    if (duration == null || !(duration instanceof Duration)) {
      return false;
    }

    return compare((Duration) duration) == DatatypeConstants.EQUAL;
  }

  /**
   * Returns a hash code consistent with the definition of the equals method.
   *
   * @see Object#hashCode()
   */
  public abstract int hashCode();

  /**
   * <p>Returns a <code>String</code> representation of this <code>Duration</code>
   * <code>Object</code>.</p>
   *
   * <p>The result is formatted according to the XML Schema 1.0 spec and can be always parsed back
   * later into the equivalent <code>Duration</code> <code>Object</code> by {@link
   * DatatypeFactory#newDuration(String  lexicalRepresentation)}.</p>
   *
   * <p>Formally, the following holds for any <code>Duration</code> <code>Object</code> x:</p>
   * <pre>
   * new Duration(x.toString()).equals(x)
   * </pre>
   *
   * @return A non-<code>null</code> valid <code>String</code> representation of this
   * <code>Duration</code>.
   */
  public String toString() {

    StringBuffer buf = new StringBuffer();

    if (getSign() < 0) {
      buf.append('-');
    }
    buf.append('P');

    BigInteger years = (BigInteger) getField(DatatypeConstants.YEARS);
    if (years != null) {
      buf.append(years + "Y");
    }

    BigInteger months = (BigInteger) getField(DatatypeConstants.MONTHS);
    if (months != null) {
      buf.append(months + "M");
    }

    BigInteger days = (BigInteger) getField(DatatypeConstants.DAYS);
    if (days != null) {
      buf.append(days + "D");
    }

    BigInteger hours = (BigInteger) getField(DatatypeConstants.HOURS);
    BigInteger minutes = (BigInteger) getField(DatatypeConstants.MINUTES);
    BigDecimal seconds = (BigDecimal) getField(DatatypeConstants.SECONDS);
    if (hours != null || minutes != null || seconds != null) {
      buf.append('T');
      if (hours != null) {
        buf.append(hours + "H");
      }
      if (minutes != null) {
        buf.append(minutes + "M");
      }
      if (seconds != null) {
        buf.append(toString(seconds) + "S");
      }
    }

    return buf.toString();
  }

  /**
   * <p>Turns {@link BigDecimal} to a string representation.</p>
   *
   * <p>Due to a behavior change in the {@link BigDecimal#toString()}
   * method in JDK1.5, this had to be implemented here.</p>
   *
   * @param bd <code>BigDecimal</code> to format as a <code>String</code>
   * @return <code>String</code> representation of <code>BigDecimal</code>
   */
  private String toString(BigDecimal bd) {
    String intString = bd.unscaledValue().toString();
    int scale = bd.scale();

    if (scale == 0) {
      return intString;
    }

        /* Insert decimal point */
    StringBuffer buf;
    int insertionPoint = intString.length() - scale;
    if (insertionPoint == 0) { /* Point goes right before intVal */
      return "0." + intString;
    } else if (insertionPoint > 0) { /* Point goes inside intVal */
      buf = new StringBuffer(intString);
      buf.insert(insertionPoint, '.');
    } else { /* We must insert zeros between point and intVal */
      buf = new StringBuffer(3 - insertionPoint + intString.length());
      buf.append("0.");
      for (int i = 0; i < -insertionPoint; i++) {
        buf.append('0');
      }
      buf.append(intString);
    }
    return buf.toString();
  }


  /**
   * <p>Calls the {@link Calendar#getTimeInMillis} method.
   * Prior to JDK1.4, this method was protected and therefore
   * cannot be invoked directly.</p>
   *
   * <p>TODO: In future, this should be replaced by <code>cal.getTimeInMillis()</code>.</p>
   *
   * @param cal <code>Calendar</code> to get time in milliseconds.
   * @return Milliseconds of <code>cal</code>.
   */
  private static long getCalendarTimeInMillis(final Calendar cal) {
    return cal.getTime().getTime();
  }
}
